PCSC winscard.h smart card API

Functions
LONG	SCardEstablishContext (DWORD dwScope, LPCVOID pvReserved1, LPCVOID pvReserved2, LPSCARDCONTEXT phContext)
LONG	SCardReleaseContext (SCARDCONTEXT hContext)
LONG	SCardConnect (SCARDCONTEXT hContext, LPCSTR szReader, DWORD dwShareMode, DWORD dwPreferredProtocols, LPSCARDHANDLE phCard, LPDWORD pdwActiveProtocol)
LONG	SCardReconnect (SCARDHANDLE hCard, DWORD dwShareMode, DWORD dwPreferredProtocols, DWORD dwInitialization, LPDWORD pdwActiveProtocol)
LONG	SCardDisconnect (SCARDHANDLE hCard, DWORD dwDisposition)
LONG	SCardStatus (SCARDHANDLE hCard, LPSTR mszReaderName, LPDWORD pcchReaderLen, LPDWORD pdwState, LPDWORD pdwProtocol, LPBYTE pbAtr, LPDWORD pcbAtrLen)
LONG	SCardGetStatusChange (SCARDCONTEXT hContext, DWORD dwTimeout, LPSCARD_READERSTATE rgReaderStates, DWORD cReaders)
LONG	SCardTransmit (SCARDHANDLE hCard, const SCARD_IO_REQUEST *pioSendPci, LPCBYTE pbSendBuffer, DWORD cbSendLength, SCARD_IO_REQUEST *pioRecvPci, LPBYTE pbRecvBuffer, LPDWORD pcbRecvLength)
LONG	SCardListReaders (SCARDCONTEXT hContext, LPCSTR mszGroups, LPSTR mszReaders, LPDWORD pcchReaders)
LONG	SCardFreeMemory (SCARDCONTEXT hContext, LPCVOID pvMem)
LONG	SCardCancel (SCARDCONTEXT hContext)
LONG	SCardIsValidContext (SCARDCONTEXT hContext)
LONG	SCardSetAttrib (SCARDHANDLE hCard, DWORD dwAttrId, LPCBYTE pbAttr, DWORD cbAttrLen)
LONG	SCardGetAttrib (SCARDHANDLE hCard, DWORD dwAttrId, LPBYTE pbAttr, LPDWORD pcbAttrLen)
LONG	SCardListReaderGroups (SCARDCONTEXT hContext, LPSTR mszGroups, LPDWORD pcchGroups)
LONG	SCardControl (SCARDHANDLE hCard, DWORD dwControlCode, LPCVOID pbSendBuffer, DWORD cbSendLength, LPVOID pbRecvBuffer, DWORD cbRecvLength, LPDWORD lpBytesReturned)
LONG	SCardBeginTransaction (SCARDHANDLE hCard)
LONG	SCardEndTransaction (SCARDHANDLE hCard, DWORD dwDisposition)

---

Detailed Description

---

Function Documentation

LONG SCardBeginTransaction

(

SCARDHANDLE

hCard

)

This function is not implemented for iOS.

Returns:

Always returns ENOSYS

LONG SCardCancel

(

SCARDCONTEXT

hContext

)

Cancels an ongoing SCardGetStatusChange() operation. Note that this function will cancel operations for all open contexts, not only operations within the hContext parameter context.

Parameters:

[in]

hContext

Context parameter received from a previous call to SCardEstablishContext().

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardConnect	(	SCARDCONTEXT	hContext,
		LPCSTR	szReader,
		DWORD	dwShareMode,
		DWORD	dwPreferredProtocols,
		LPSCARDHANDLE	phCard,
		LPDWORD	pdwActiveProtocol
	)

Establishes a connection between the calling application and a smart card contained by a specific reader. If no card exists in the specified reader, an error is returned.

Parameters:

[in]	hContext	Context parameter received from a previous call to SCardEstablishContext().
[in]	szReader	The name of the reader that contains the target card
[in]	dwShareMode	A flag that indicates whether other applications may form connections to the card. At the moment only SCARD_SHARE_EXCLUSIVE() is a valid value.
[in]	dwPreferredProtocols	A bitmask of acceptable protocols for the connection. See card protocol for valid values.
[out]	phCard	A handle that identifies the connection to the smart card in the designated reader.
[out]	pdwActiveProtocol	Flag that indicates the established active protocol. See card protocol for valid values.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardControl	(	SCARDHANDLE	hCard,
		DWORD	dwControlCode,
		LPCVOID	pbSendBuffer,
		DWORD	cbSendLength,
		LPVOID	pbRecvBuffer,
		DWORD	cbRecvLength,
		LPDWORD	lpBytesReturned
	)

This function is not implemented for iOS.

Returns:

Always returns ENOSYS

LONG SCardDisconnect	(	SCARDHANDLE	hCard,
		DWORD	dwDisposition
	)

Terminates a connection previously opened between the calling application and a smart card in the target reader.

Parameters:

[in]	hCard	Reference value obtained from a previous call to SCardConnect().
[in]	dwDisposition	Action to take on the card in the connected reader on close. See card disposition for valid values.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardEndTransaction	(	SCARDHANDLE	hCard,
		DWORD	dwDisposition
	)

This function is not implemented for iOS.

Returns:

Always returns ENOSYS

LONG SCardEstablishContext	(	DWORD	dwScope,
		LPCVOID	pvReserved1,
		LPCVOID	pvReserved2,
		LPSCARDCONTEXT	phContext
	)

Initializes the ExternalAccessory framework enabling communications with the Precise Biometrics iOS smart card reader.

Parameters:

[in]	dwScope	Scope of the resource manager context. Only SCARD_SCOPE_USER and SCARD_SCOPE_SYSTEM are valid values.
[in]	pvReserved1	Reserved for future use and must be NULL.
[in]	pvReserved2	Reserved for future use and must be NULL.
[out]	phContext	A handle to the established resource manager context. This handle can now be supplied to other functions attempting to do work within this context.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardFreeMemory	(	SCARDCONTEXT	hContext,
		LPCVOID	pvMem
	)

Releases memory that has been returned from the resource manager using the SCARD_AUTOALLOCATE length designator.

Parameters:

[in]	hContext	Context parameter received from a previous call to SCardEstablishContext().
	pvMem	Memory block to be released.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardGetAttrib	(	SCARDHANDLE	hCard,
		DWORD	dwAttrId,
		LPBYTE	pbAttr,
		LPDWORD	pcbAttrLen
	)

Retrieves a reader/context attribute. Supported attributes are: SCARD_ATTR_AUTO_BACKGROUND_HANDLING - can be used to the retrieve the current state of the automatic background handling.

Parameters:

[in]	hCard	Reference value obtained from a previous call to SCardConnect(). Ignored when used together with SCARD_ATTR_AUTO_BACKGROUND_HANDLING.
[in]	dwAttrId	Specifies the identifier for the attribute to get.
[out]	pbAttr	Pointer to a buffer that receives the attribute whose ID is supplied in dwAttrId. If this value is NULL, SCardGetAttrib ignores the buffer length supplied in pcbAttrLen, writes the length of the buffer that would have been returned if this parameter had not been NULL to pcbAttrLen, and returns a success code.
[in,out]	pcbAttrLen	Length of the pbAttr buffer in bytes, and receives the actual length of the received attribute If the buffer length is specified as SCARD_AUTOALLOCATE, then pbAttr is converted to a pointer to a byte pointer, and receives the address of a block of memory containing the attribute. This block of memory must be deallocated with SCardFreeMemory.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardGetStatusChange	(	SCARDCONTEXT	hContext,
		DWORD	dwTimeout,
		LPSCARD_READERSTATE	rgReaderStates,
		DWORD	cReaders
	)

Blocks execution until the current availability of the cards in a specific set of readers changes. The caller supplies a list of readers to be monitored by an SCARD_READERSTATE array and the maximum amount of time (in milliseconds) that it is willing to wait for an action to occur on one of the listed readers. Note that SCardGetStatusChange() uses the user-supplied value in the dwCurrentState members of the rgReaderStates SCARD_READERSTATE array as the definition of the current state of the readers. The function returns when there is a change in availability, having filled in the dwEventState members of rgReaderStates appropriately.

Parameters:

[in]	hContext	Context parameter received from a previous call to SCardEstablishContext().
[in]	dwTimeout	The maximum amount of time, in milliseconds, to wait for an action. A value of zero causes the function to return immediately. A value of INFINITE causes this function never to time out.
	rgReaderStates	An array of SCARD_READERSTATE structures that specify the readers to watch, and that receives the result.
	cReaders	The number of elements in the rgReaderStates array.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardIsValidContext

(

SCARDCONTEXT

hContext

)

Determines whether a context handle is valid.

Parameters:

[in]

hContext

Context parameter received from a previous call to SCardEstablishContext().

Returns:

SCARD_S_SUCCESS if the context is valid.

SCARD_E_INVALID_HANDLE if the context is invalid.

LONG SCardListReaderGroups	(	SCARDCONTEXT	hContext,
		LPSTR	mszGroups,
		LPDWORD	pcchGroups
	)

This function is not implemented for iOS.

Returns:

Always returns ENOSYS

LONG SCardListReaders	(	SCARDCONTEXT	hContext,
		LPCSTR	mszGroups,
		LPSTR	mszReaders,
		LPDWORD	pcchReaders
	)

Provides a list of currently available smart card readers.

Parameters:

[in]	hContext	Context parameter received from a previous call to SCardEstablishContext().
[in]	mszGroups	Use a NULL value to list all readers in the system.
[out]	mszReaders	Multi-string that lists the card readers currently connected and available to the system. If this value is NULL, SCardListReaders ignores the buffer length supplied in pcchReaders, writes the length of the buffer that would have been returned if this parameter had not been NULL to pcchReaders, and returns a success code.
[in,out]	pcchReaders	Length of the mszReaders buffer in characters. This parameter receives the actual length of the multi-string structure, including all trailing null characters. If the buffer length is specified as SCARD_AUTOALLOCATE, then mszReaders is converted to a pointer to a byte pointer, and receives the address of a block of memory containing the multi-string structure. This block of memory must be deallocated with SCardFreeMemory().

Returns:

Returns SCARD_S_SUCCESS if at least one reader is connected and available to the system. Returns SCARD_E_NO_READERS_AVAILABLE if no reader can be found. Otherwise an error code is returned. See error codes for valid return values

LONG SCardReconnect	(	SCARDHANDLE	hCard,
		DWORD	dwShareMode,
		DWORD	dwPreferredProtocols,
		DWORD	dwInitialization,
		LPDWORD	pdwActiveProtocol
	)

reestablishes an existing connection between the calling application and a smart card. This function moves a card handle from direct access to general access, or acknowledges and clears an error condition that is preventing further access to the card.

Parameters:

[in]	hCard	Reference value obtained from a previous call to SCardConnect().
[in]	dwShareMode	A flag that indicates whether other applications may form connections to the card. At the moment only SCARD_SHARE_EXCLUSIVE is a valid value.
[in]	dwPreferredProtocols	A bitmask of acceptable protocols for the connection. See card protocol for valid values.
[in]	dwInitialization	Type of initialization that should be performed on the card. See card disposition for valid values.
[out]	pdwActiveProtocol	Flag that indicates the established active protocol. See card protocol for valid values.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardReleaseContext

(

SCARDCONTEXT

hContext

)

Releases the session to the accessory and the ExternalAccessory framework when the last context is released. Any smart card present in the reader will be powered off automatically.

Parameters:

[in]

hContext

Context parameter received from a previous call to SCardEstablishContext().

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardSetAttrib	(	SCARDHANDLE	hCard,
		DWORD	dwAttrId,
		LPCBYTE	pbAttr,
		DWORD	cbAttrLen
	)

Sets a reader/context attribute. Supported attributes are: SCARD_ATTR_AUTO_BACKGROUND_HANDLING. See the doucment "Precise iOS Toolkit User Manual" in the toolkit for further information. The behaviour of the smart card library if this functionality is disabled and the application does not handle all relevant iOS events is undefined. This feature is global. Changing the value will affect all open contexts and sessions.

Parameters:

[in]	hCard	Reference value obtained from a previous call to SCardConnect(). Ignored when used together with SCARD_ATTR_AUTO_BACKGROUND_HANDLING.
[in]	dwAttrId	Specifies the identifier for the attribute to set.
[in]	pbAttr	Pointer to a buffer that supplies the attribute whose identifier is supplied in dwAttrId.
[in]	cbAttrLen	Count of bytes that represent the length of the attribute value in the pbAttr buffer.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardStatus	(	SCARDHANDLE	hCard,
		LPSTR	mszReaderName,
		LPDWORD	pcchReaderLen,
		LPDWORD	pdwState,
		LPDWORD	pdwProtocol,
		LPBYTE	pbAtr,
		LPDWORD	pcbAtrLen
	)

provides the current status of a smart card in a reader. You can call it any time after a successful call to SCardConnect() and before a successful call to SCardDisconnect(). It does not affect the state of the reader or reader driver.

Parameters:

[in]	hCard	Reference value returned from SCardConnect().
[out]	mszReaderName	List of display names (multiple string) by which the currently connected reader is known.
[in,out]	pcchReaderLen	On input, supplies the length of the szReaderName buffer. On output, receives the actual length (in characters) of the reader name list, including the trailing NULL character. If this buffer length is specified as SCARD_AUTOALLOCATE, then szReaderName is converted to a pointer to a byte pointer, and it receives the address of a block of memory that contains the multiple-string structure.
[out]	pdwState	Current state of the smart card in the reader. Upon success, it receives one of the following state indicators. See smart card states for valid values.
[out]	pdwProtocol	Current protocol, if any.
[out]	pbAtr	Pointer to a 32-byte buffer that receives the ATR string from the currently inserted card, if available.
[in,out]	pcbAtrLen	On input, supplies the length of the pbAtr buffer. On output, receives the number of bytes in the ATR string (32 bytes maximum). If this buffer length is specified as SCARD_AUTOALLOCATE, then pbAtr is converted to a pointer to a byte pointer, and it receives the address of a block of memory that contains the multiple-string structure.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values

LONG SCardTransmit	(	SCARDHANDLE	hCard,
		const SCARD_IO_REQUEST *	pioSendPci,
		LPCBYTE	pbSendBuffer,
		DWORD	cbSendLength,
		SCARD_IO_REQUEST *	pioRecvPci,
		LPBYTE	pbRecvBuffer,
		LPDWORD	pcbRecvLength
	)

The SCardTransmit function sends a service request to the smart card and expects to receive data back from the card.

Parameters:

[in]	hCard	Reference value returned from SCardConnect().
[in]	pioSendPci	pointer to the protocol header structure for the instruction. This buffer is in the format of an SCARD_IO_REQUEST structure, followed by the specific protocol control information (PCI). For the T=0, T=1, and Raw protocols, the PCI structure is constant. The smart card subsystem supplies a global T=0, T=1, or Raw PCI structure, which you can reference by using the PCI structures respectively.
[in]	pbSendBuffer	A pointer to the actual data to be written to the card.
[in]	cbSendLength	The length, in bytes, of the pbSendBuffer parameter.
[out]	pioRecvPci	Pointer to the protocol header structure for the instruction, followed by a buffer in which to receive any returned protocol control information (PCI) specific to the protocol in use. This parameter can be NULL if no PCI is returned.
[out]	pbRecvBuffer	Pointer to any data returned from the card.
[in,out]	pcbRecvLength	Supplies the length, in bytes, of the pbRecvBuffer parameter and receives the actual number of bytes received from the smart card. This value cannot be SCARD_AUTOALLOCATE because SCardTransmit() does not support SCARD_AUTOALLOCATE.

Returns:

SCARD_S_SUCCESS if successful. Otherwise an error code is returned. See error codes for valid return values